home *** CD-ROM | disk | FTP | other *** search
/ Risc World 3 / Risc World 3.iso / SOFTWARE / ISSUE6 / PD / VERMA / !Verma / !Help < prev    next >
Text File  |  2003-03-11  |  18KB  |  475 lines
  1.  
  2. —————————————————————————————  !Verma  (0.21)  —————————————————————————————
  3.  
  4.                           Copyright, MidiWays 1998
  5.  
  6.                                Author : Lenny
  7.  
  8. ————————————————————————————————————————————————————————————————————————————
  9.  
  10. 0.0  Contents
  11.      ========
  12.  
  13.      1.0  Overview
  14.      1.1    Features
  15.      1.2    Limitations
  16.      2.0  Iconbar
  17.      2.1    Iconbar menu
  18.      3.0  Modules in ROM/RMA
  19.      3.1    ROM/RMA list menu
  20.      3.2    Module menu
  21.      4.0  Directory scanning
  22.      4.1    Viewer menu
  23.      5.0  The Module Detail window
  24.      6.0  The Save window
  25.      7.0  The Find window
  26.      8.0  Scanning options
  27.      9.0  Contacting the author
  28.  
  29. ————————————————————————————————————————————————————————————————————————————
  30.  
  31. 1.0  Overview :
  32.      ========
  33.  
  34. !Verma is a utility that displays version, etc information about
  35. relocatable modules, both those in memory (ROM/RMA) and those on disc
  36. (filetype &FFA) - in the latter case without the need to first install
  37. them in the RMA.  These two types of module list involve different sets of
  38. data, so two different window layouts are used.  Throughout this document
  39. I refer to the former as the ROM/RMA window (or list) and to the latter as
  40. a Viewer.
  41.  
  42. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  43.  
  44. 1.1  Features :
  45.      ========
  46.  
  47.  * Lists modules in memory (ROMs and/or RMA), showing each module's main
  48.    details.  [ as of v0.20 ]
  49.  
  50.     * The familiar module maintainance commands are available from a menu,
  51.       as is the ability to extract ROM modules, saving them to disc.
  52.  
  53.  * Module files or directories (including application dirs) may be dragged
  54.    to !Verma's iconbar icon, whereupon it will display a window showing
  55.    all modules found.
  56.  
  57.     * Options available from the iconbar menu allow scanning to recurse
  58.       and/or include neighbouring objects.
  59.  
  60.     * Multiple Viewers are supported (handy if you want to compare
  61.       directories of modules).
  62.  
  63.     * Support for long filenames (though leafnames are displayed truncated
  64.       to 12 characters).  [ as of v0.17 ]
  65.  
  66.     * Multiple occurances of modules are indicated.
  67.  
  68.     * Modules that are present in the RMA are indicated as such (by
  69.       showing the version number of that in the RMA).
  70.  
  71.     * Clicking Shift-SELECT on an item in a Viewer will perform a
  72.       Filer_OpenDir revealing that object.
  73.  
  74.  * Both types of module list (memory or disc based) use the current
  75.    Desktop font if this is available (ie if the Nested Wimp version of the
  76.    WindowManager is present), otherwise the System font is used.
  77.  
  78.  * The contents of module lists can be saved as a Text file (to disc or
  79.    direct to another application).
  80.  
  81.  * Module lists can be searched for specific modules.  [ as of v0.19 ]
  82.  
  83.  * A Detail window (listing individual SWIs) can be opened from either
  84.    type of module list window.  [ as of v0.20 ]
  85.  
  86.  * Clicking on a SWI name in the Detail window will attempt a StrongHelp
  87.    lookup, first loading StrongHelp if necessary/possible.
  88.  
  89.  * A Dynamic Area will be used if the facility is available.  If DA's are
  90.    not available, then application space is used.  [ as of v0.13 ]
  91.  
  92.  * Support for interactive help.  [ as of v0.20 ]
  93.  
  94.  * 26/32-bit neutral.  [ as of v0.20 ]
  95.  
  96. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  97.  
  98. 1.2  Limitations :
  99.      ===========
  100.  
  101.  * Module files that are compressed (eg PPP, AcornURI) are indicated as
  102.    such, though are not decompressed.  Hence any SWI or flags information
  103.    for these is not revealed.  This does not apply to ROM/RMA modules.
  104.  
  105.  * There is no facility for listing individual * commands provided by a
  106.    module.
  107.  
  108.  * Directory scanning doesn't multitask.  Sorry about that, though the
  109.    ESCAPE key can be used to abort a lengthy scan.
  110.  
  111.  * The sort order of the ROM/RMA window's contents is less than ideal when
  112.    displaying only RMA modules.
  113.  
  114. Any or all of these shortcomings may be addressed in future versions.
  115.  
  116. ————————————————————————————————————————————————————————————————————————————
  117.  
  118. 2.0  Iconbar :
  119.      =======
  120.  
  121.  * Click SELECT on the iconbar icon to Open/Surface the ROM/RMA Modules
  122.    window.
  123.  
  124.  * Click ADJUST on the iconbar icon to Open/Close the ROM/RMA Modules
  125.    window.  When closing the ROM/RMA window, the Detail window will also
  126.    be closed if its contents relate to a ROM/RMA based module.
  127.  
  128.  * Click MENU on the iconbar icon to open the iconbar menu.
  129.  
  130. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  131.  
  132. 2.1  Iconbar menu :
  133.      ============
  134.  
  135.  * Info : The usual.  Additionally, it contains a pair of buttons :
  136.    * Email : Attempts to open a Write email window (addressed to me).
  137.    * Web   : Attempts to log onto my web site (software area).
  138.  
  139.  * Help : Runs this text file.
  140.  
  141.  * Options : Leads to the Options submenu :
  142.  
  143.    * Neighbours : When ticked, scanning will include objects that are in
  144.      the same directory as the dragged object.
  145.  
  146.    * Recurse : When ticked, scanning recurses down the directory tree.
  147.  
  148.    * Expanded pane : When ticked, Viewers will be opened with their pane
  149.      already expanded (ie showing the additional Info field).  See section
  150.      4.0.
  151.  
  152.  * Close all : Closes all open Viewer windows.  The Detail window will
  153.    also be closed if its contents relate to a disc based module.
  154.  
  155.  * Quit : The usual.
  156.  
  157. ————————————————————————————————————————————————————————————————————————————
  158.  
  159. 3.0  Modules in ROM/RMA :
  160.      ==================
  161.  
  162. Other programs offering similar features take the approach of presenting
  163. information about ROM and RMA modules in separate windows.  !Verma uses a
  164. single window which can be made to display either ROM or RMA modules, or
  165. (uniquely, I believe) both together (using the popup Show menu in the
  166. window's toolbar pane).
  167.  
  168. The following is shown for each module :
  169.  
  170.  * ROM : the ROM location or '-' if not a ROM-based module.  Modules in
  171.    the system ROM are listed from 0 onwards, whereas modules from
  172.    expansion card ROMs are shown with the format 'c:m', where 'c' is the
  173.    expansion card number and 'm' is the ROM location within that ROM
  174.    section (each 0 onwards).
  175.  
  176.  * RMA : the RMA location or '-' if not in the RMA (ie it's Dormant or
  177.    Unplugged).
  178.  
  179.  * Status : ROM modules have four possible states - Unplugged, Dormant
  180.    (displaced by a module loaded into the RMA), Active or Running (as the
  181.    currently paged application).  Modules that have been loaded from disc
  182.    are shown as Loaded, to distinguish them from ROM sourced modules.
  183.    Note that you'll never see Running in !Verma's window as, at the time
  184.    the information is gathered, !Verma is the current task and it isn't a
  185.    module :o)
  186.  
  187.  * Address : the address in memory at which the module resides.  This is
  188.    coloured green for ROM-based modules that are running from their ROM
  189.    location.  Modules running from the RMA, ie loaded from ROM (eg using
  190.    RMFaster) or from disc are coloured blue.
  191.  
  192.  * Workspace : this is actually the module's 'private word', which is
  193.    generally used as a workspace pointer (into RMA space), though not
  194.    always.  If this is zero, '-' is shown.  Non-zero values deemed not to
  195.    be a valid pointer are coloured red.
  196.  
  197.  * Title : the module's title, and if mutiply instantiated, including the
  198.    instantiation postfix.
  199.  
  200.  * Version : the module's version and date details.
  201.  
  202.  * 32b : the state of the 32-bit-safe flag (Y or N). '-' is shown if there
  203.    is no module flags word (equivalent to N).
  204.  
  205.  * SWIs : the number of SWIs provided by this module.
  206.  
  207.  * Chunk : the base SWI number for this module, or '-' if no SWIs.
  208.  
  209.  * Prefix : the SWI name prefix, or '-' if no SWIs.
  210.  
  211. Note that for Dormant and Unplugged modules, only the ROM location,
  212. Status, Title and Version (excluding date) details are shown.
  213.  
  214.  
  215. Clicking SELECT or ADJUST on an entry in this window will open/close the
  216. Module Detail window listing individual SWIs etc.  See section 5.0.
  217.  
  218.  
  219. Due to way the ROM and RMA modules are combined into a single list, they
  220. are not listed in strict numerical sequence (ROM/RMA location), which may
  221. initially confuse (especially when showing RMA modules only), though there
  222. is a logic to it, as follows :
  223.  
  224.  * The ROM modules are enumerated first, a process which gives minimal
  225.    information about each module (just title and version, exc date).
  226.  
  227.  * Then the RMA is enumerated, this process revealing greater detail per
  228.    module.  Each module is compared with the ROM modules already listed :
  229.  
  230.     * Any that match on title and version are obviously ROM modules that
  231.       are active/running, so the additional info is used to fill out this
  232.       existing entry.  (cf other software that lists ROM modules
  233.       separately, and thus with just the minimal details.)
  234.       Only Dormant and Unplugged modules are shown with minimal info.
  235.  
  236.     * Any that match on title but not on version are modules that have
  237.       been loaded from disc, displacing the ROM based version.  These are
  238.       inserted in the list immediately after the matching entry.
  239.       This has the advantage that dormant/unplugged modules and any
  240.       replacement are listed together.
  241.  
  242.     * The remainder must have been loaded from disc, their details being
  243.       added to the end of the list.
  244.  
  245. So, there isn't a problem when showing ROM modules only, ie they are
  246. listed in correct numerical sequence.  When showing both ROM and RMA
  247. modules, they are (intentially) interleaved as described above.  However,
  248. it is due to this interleaving process, that when showing RMA modules
  249. only, the sequence is less than ideal.
  250.  
  251. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  252.  
  253. 3.1  ROM/RMA list menu :
  254.      =================
  255.  
  256. Available by clicking MENU anywhere in the ROM/RMA Modules window.
  257.  
  258.  * Info : The same as on the iconbar menu.
  259.  
  260.  * Module : Leads to the Module submenu.  See section 3.2.
  261.  
  262.  * Refresh : Rescans the RMA and updates the window's contents.
  263.  
  264.  * Save : Leads to the Save window, enabling you to save the window's
  265.    contents as a Text file.  See section 6.0.
  266.  
  267.  * Find : Leads to the Find window, enabling you to search for specific
  268.    modules.  See section 7.0.
  269.  
  270.  * Clear : Removes any highlighting (resulting from a Find operation).
  271.  
  272. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  273.  
  274. 3.2  Module menu :
  275.      ===========
  276.  
  277.  * Enter : Start a module as a task.
  278.    Only modules in the RMA, that can be started as an application (ie with
  279.    a valid non-zero start address).
  280.  
  281.  * ReInit : Reinitialises a module, reversing Unplug status if necessary.
  282.    Any modules, except Dormant/Unplugged for which there's a later version
  283.    in the RMA.
  284.  
  285.  * Insert : Reverses effect of Unplug, but does not reinitialise a module.
  286.    Only Unplugged ROM modules, that don't have a later version in the RMA.
  287.  
  288.  * Faster : Moves a module from ROM to RAM.
  289.    Only system ROM modules (ie exc podule-based modules) that are not
  290.    Unplugged or Dormant, and that are running from their ROM address.
  291.    (Podule ROM based modules are always run from RAM anyway.)
  292.  
  293.  * Kill : Kills and deletes a module.
  294.    Any modules in the RMA.
  295.  
  296.  * Unplug : Prevent a module from being initialised upon a reset.
  297.    Only for Active ROM modules, or Dormant ones for which there isn't a
  298.    later version in the RMA.
  299.  
  300.  * Extract : Save a ROM module to disc.
  301.    Only for Active/Running ROM modules.
  302.  
  303. ————————————————————————————————————————————————————————————————————————————
  304.  
  305. 4.0  Directory scanning :
  306.      ==================
  307.  
  308. Simply drag a Module file (or directory of) to !Verma's iconbar icon.
  309.  
  310. In obeyance with the scanning options (Neighbours and Recurse) a Viewer
  311. window is opened showing all modules found, listing for each module :
  312.  
  313.  * Leafname, Title and Version/Date.
  314.  
  315.  * If a module with the same title is already in the RMA, then its version
  316.    number is shown, for easy comparison.  This is coloured grey if the RMA
  317.    version is more recent, or red if the disc version is the more recent.
  318.  
  319.  * The state of the 32-bit-safe flag, if present, is shown (a '-'
  320.    indicates there is no flags word).
  321.  
  322.  * For modules that provide SWIs, the number of SWIs, the Chumk number (in
  323.    hex) and the SWI Prefix are also shown.
  324.  
  325. A Viewer's pane area can be expanded (using the top-right triangular
  326. button) revealing an extra Info icon, that gives additional info re the
  327. module currently under the pointer (the full filename, help string, module
  328. flags, or SWI area).
  329.  
  330. Multiple Viewers are supported, and you can also drag a module (or
  331. directory of) into an already open Viewer to replace its contents.
  332.  
  333. If you wish to interrupt a lengthy scan, press the ESCAPE key.
  334.  
  335. Multiple occurances of modules (ie with the same Title) are indicated, by
  336. the red numbers on the left of the Viewer.  The 'M' in the header pane is
  337. coloured red if any multiple occurances are found, or black if there are
  338. none.
  339.  
  340.  
  341. Clicking SELECT or ADJUST on an entry in this window will open/close the
  342. Module Detail window listing individual SWIs etc.  See section 5.0.
  343.  
  344. Clicking Shift-SELECT on an entry in a Viewer will perform a Filer_OpenDir
  345. revealing that object.
  346.  
  347.  
  348. Viewer windows have their own menu.
  349.  
  350. NB.  If you wish to recursively scan an object which is located in your
  351.      hard disc's root directory (eg !Boot), then it is probably a good
  352.      idea to untick Neighbours, as otherwise !Verma will attempt to scan
  353.      the ENTIRE disc, which will probably take a while.
  354.  
  355. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  356.  
  357. 4.1  Viewer menu :
  358.      ===========
  359.  
  360.  * Info : The same as on the iconbar menu.
  361.  
  362.  * Save : Leads to the Save window, enabling you to save the window's
  363.    contents as a Text file.  See section 6.0.
  364.  
  365.  * Find : Leads to the Find window, enabling you to search for specific
  366.    modules.  See section 7.0.
  367.  
  368.  * Clear : Removes any highlighting (resulting from a Find operation).
  369.  
  370. ————————————————————————————————————————————————————————————————————————————
  371.  
  372. 5.0  The Module Detail window
  373.      ========================
  374.  
  375. This window can be opened from either type of module list.
  376.  
  377. The upper pane shows the module's title and version/date information,
  378. whether it is located in ROM, RMA or on disc, and the version that is
  379. currently active in the RMA (if any at all).
  380.  
  381. The main window area lists any SWIs that are provided by this module.
  382. Clicking on a SWI entry will attempt to perform a StrongHelp lookup,
  383. loading StrongHelp first if necessary (and if 'seen').
  384.  
  385. This window doesn't have a menu.
  386.  
  387. ————————————————————————————————————————————————————————————————————————————
  388.  
  389. 6.0  The Save window :
  390.      ===============
  391.  
  392. The Save window allows the contents of a module list to be saved as a Text
  393. file (to disc or direct to another application).  Switches in the Save
  394. window provide control over the degree of detail.
  395.  
  396. ————————————————————————————————————————————————————————————————————————————
  397.  
  398. 7.0  The Find window :
  399.      ===============
  400.  
  401. The Find window allows the contents of a module list to be searched for
  402. specific modules.  Radio icons allow you to search by Title, Help text,
  403. SWI chunk number, SWI prefix, or for all instances of a given multiple
  404. occurance (if searching the ROM/RMA list, then Help text and Multiple are
  405. faded, as searching these fields is not possible) :
  406.  
  407.  * Title, Help text, SWI prefix :
  408.    A case-insensitive substring search is performed.
  409.  
  410.  * Chunk number :
  411.    6 hex characters (max).  Any number of '#' characters may be used as
  412.    single character wildcards.
  413.  
  414.  * Multiple occurance :
  415.    Use the bump icons to specify the instance (equating to the number
  416.    shown in red on the left of the Viewer display).
  417.  
  418. Click on Find to perform a fresh search whereupon each row for which a
  419. match was found is highlighted.  This highlighting remains until another
  420. search is performed or the relevant menu's Clear option is used.
  421.  
  422. Clicking on Find Also will not clear any previous highlighting prior to
  423. performing the search.
  424.  
  425. ————————————————————————————————————————————————————————————————————————————
  426.  
  427. 8.0  Scanning options :
  428.      ================
  429.  
  430. Sorry this bit isn't in English, though a truth table should at least be
  431. unambiguous ...
  432.  
  433. The scope of the directory scanning when a filer object is dragged to
  434. !Verma's iconbar icon is determined by three factors - whether a module
  435. file or a directory/app is dragged to !Verma, and the state of the two
  436. options, Neighbours and Recurse :
  437.  
  438.   Obj = the object dragged to !Verma (M=Module, D=Directory)
  439.   N   = state of Neighbours option (1=ticked, 0=not ticked)
  440.   R   = state of Recurse option (1=ticked, 0=not ticked)
  441.  
  442.   'parent' is the directory in which the 'object' resides.
  443.  
  444.   --------------------------------------------------------------------
  445.    Obj  R   N   |  Display                           |  Re.
  446.   --------------------------------------------------------------------
  447.     M   0   0   |  A single module                   |  object
  448.     M   0   1   |  All modules in a single dir       |  parent
  449.     M   1   0   |  A single module                   |  object
  450.     M   1   1   |  All modules in a dir recursively  |  parent
  451.     D   0   0   |  All modules in a single dir       |  object
  452.     D   0   1   |  All modules in 2 dirs             |  parent+object
  453.     D   1   0   |  All modules in a dir recursively  |  object
  454.     D   1   1   |  All modules in a dir recursively  |  parent
  455.   --------------------------------------------------------------------
  456.  
  457. ————————————————————————————————————————————————————————————————————————————
  458.  
  459. 9.0  Contacting the author
  460.      =====================
  461.  
  462. For bug reports, suggestions, sighs of adulation, derisive comments or
  463. submission of gratuities, please contact :
  464.  
  465.   snail:  Lenny
  466.           MidiWays
  467.           204 Amelia Street
  468.           Walworth
  469.           London
  470.           SE17 3AS
  471.  
  472.   email:  lenny@argonet.co.uk    (Use the button in the Info window.)
  473.  
  474. ————————————————————————————————————————————————————————————————————————————
  475.